Frontend API-yhdyskäytävä: GraphQL-federaatio ja skeemojen yhdistäminen

Modernien verkkosovellusten kehitysmaailmassa useista lähteistä peräisin olevan datan hallinta voi olla merkittävä haaste. Sovellusten monimutkaistuessa ja siirtyessä mikropalveluarkkitehtuureihin, tarve yhtenäiselle ja tehokkaalle tavalle datan käyttöön korostuu. Frontend API-yhdyskäytävä toimii keskitettynä pääsypisteenä asiakassovelluksille, kooten dataa useista taustapalveluista ja tarjoten virtaviivaistetun kokemuksen sekä kehittäjille että loppukäyttäjille. Tämä blogikirjoitus tutkii kahta tehokasta tekniikkaa Frontend API-yhdyskäytävän rakentamiseen: GraphQL-federaatiota ja skeemojen yhdistämistä (Schema Stitching).

Mikä on Frontend API-yhdyskäytävä?

Frontend API-yhdyskäytävä on arkkitehtuurimalli, jossa erillinen palvelin toimii välittäjänä frontend-asiakkaiden (esim. verkkoselaimet, mobiilisovellukset) ja useiden taustapalveluiden välillä. Se yksinkertaistaa datanhakua seuraavilla tavoilla:

• Datan yhdistäminen: Datan kokoaminen useista lähteistä yhteen vastaukseen.
• Datan muuntaminen: Datamuotojen mukauttaminen frontendiä varten.
• Monimutkaisuuden abstrahointi: Taustapalveluiden monimutkaisuuksien piilottaminen asiakkaalta.
• Tietoturvan valvonta: Autentikointi- ja auktorisointikäytäntöjen toteuttaminen.
• Suorituskyvyn optimointi: Usein käytetyn datan välimuistiin tallentaminen ja verkkopyyntöjen vähentäminen.

Pohjimmiltaan se toteuttaa Backend for Frontend (BFF) -mallia laajassa mittakaavassa ja antaa frontend-tiimeille enemmän valtaa käyttämiinsä API-rajapintoihin. Suuremmissa organisaatioissa se, että frontend hallinnoi ja kuratoi omia API-rajapintojaan, voi nopeuttaa toimitusta ja vähentää riippuvuutta taustajärjestelmätiimeistä.

Miksi käyttää GraphQL:ää Frontend API-yhdyskäytävässä?

GraphQL on API-rajapintojen kyselykieli ja ajonaikainen ympäristö näiden kyselyiden toteuttamiseen olemassa olevalla datalla. Se tarjoaa useita etuja perinteisiin REST API -rajapintoihin verrattuna, mikä tekee siitä sopivan Frontend API-yhdyskäytävien rakentamiseen:

• Tehokas datanhaku: Asiakkaat pyytävät vain tarvitsemansa datan, mikä vähentää ylimääräistä datansiirtoa ja parantaa suorituskykyä.
• Vahva tyypitys: GraphQL-skeemat määrittelevät datan rakenteen, mikä mahdollistaa paremmat työkalut ja validoinnin.
• Introspektio: Asiakkaat voivat selvittää saatavilla olevan datan ja operaatiot skeeman introspektion avulla.
• Reaaliaikaiset ominaisuudet: GraphQL-tilaukset (subscriptions) mahdollistavat reaaliaikaiset datapäivitykset.

Hyödyntämällä GraphQL:ää Frontend API-yhdyskäytävä voi tarjota joustavan, tehokkaan ja kehittäjäystävällisen rajapinnan datan hakemiseen useista taustapalveluista. Tämä on selkeä vastakohta perinteisille lähestymistavoille, joissa käytetään useita REST-päätepisteitä, joista jokaisesta on tehtävä erillinen kysely ja jotka usein palauttavat enemmän dataa kuin on tarpeen.

GraphQL-federaatio: Hajautettu lähestymistapa

Mitä on GraphQL-federaatio?

GraphQL-federaatio on tehokas tekniikka hajautetun GraphQL API:n rakentamiseen yhdistämällä useita GraphQL-palveluita (kutsutaan "aligraafeiksi" eli subgraphs) yhdeksi yhtenäiseksi skeemaksi. Jokainen aligraafi on vastuussa tietystä toimialueesta tai datalähteestä, ja federaatioyhdyskäytävä orkestroi kyselyt näiden aligraafien välillä.

Ydinkonsepti pyörii supergraafin ympärillä, joka on yksi yhtenäinen GraphQL-skeema, joka edustaa koko API-rajapintaa. Tämä supergraafi rakennetaan yhdistämällä pienempiä GraphQL-skeemoja, joita kutsutaan aligraafeiksi, joista kukin edustaa tiettyä mikropalvelua tai datalähdettä. Federaatioyhdyskäytävä vastaa saapuvien GraphQL-kyselyiden reitittämisestä sopiville aligraafeille ja tulosten yhdistämisestä yhdeksi vastaukseksi.

Miten GraphQL-federaatio toimii

1. Aligraafin määrittely: Jokainen mikropalvelu paljastaa GraphQL API:n (aligraafin), joka määrittelee oman datansa ja operaationsa. Nämä skeemat sisältävät direktiivejä, jotka kertovat federaatioyhdyskäytävälle, miten tyypit ja kentät ratkaistaan. Keskeisiä direktiivejä ovat `@key`, `@external` ja `@requires`.
2. Supergraafin koostaminen: Federaatioyhdyskäytävä (esim. Apollo Gateway) hakee skeemat kustakin aligraafista ja koostaa niistä yhden yhtenäisen skeeman (supergraafin). Tämä prosessi sisältää tyyppi- ja kenttäristiriitojen ratkaisemisen sekä suhteiden luomisen eri aligraafien tyyppien välille.
3. Kyselyn suunnittelu ja suoritus: Kun asiakas lähettää GraphQL-kyselyn yhdyskäytävälle, yhdyskäytävä analysoi kyselyn ja määrittää, mihin aligraafeihin on tehtävä kysely pyynnön täyttämiseksi. Sitten se jakaa kyselyn sopiville aligraafeille, kerää tulokset ja yhdistää ne yhdeksi vastaukseksi, joka palautetaan asiakkaalle.

Esimerkki: Verkkokauppa-alusta GraphQL-federaatiolla

Kuvitellaan verkkokauppa-alusta, jolla on erilliset mikropalvelut tuotteille, asiakkaille ja tilauksille.

• Tuotteiden aligraafi: Hallinnoi tuotetietoja (nimi, kuvaus, hinta jne.).
• Asiakkaiden aligraafi: Hallinnoi asiakastietoja (nimi, osoite, sähköposti jne.).
• Tilausten aligraafi: Hallinnoi tilaustietoja (tilauksen ID, asiakkaan ID, tuotteiden ID:t, kokonaissumma jne.).

Jokainen aligraafi paljastaa GraphQL API:n, ja federaatioyhdyskäytävä yhdistää nämä API:t yhdeksi supergraafiksi. Asiakas voi sitten tehdä kyselyn supergraafiin hakeakseen tietoa tuotteista, asiakkaista ja tilauksista yhdellä pyynnöllä.

Esimerkiksi kysely, jolla haetaan asiakkaan nimi ja hänen tilaushistoriansa, voisi näyttää tältä:

query GetCustomerAndOrders($customerId: ID!) {
  customer(id: $customerId) {
    id
    name
    orders {
      id
      orderDate
      totalAmount
    }
  }
}

Federaatioyhdyskäytävä reitittäisi tämän kyselyn Asiakkaiden ja Tilausten aligraafeihin, hakisi tarvittavat tiedot ja yhdistäisi ne yhdeksi vastaukseksi.

GraphQL-federaation edut

• Yksinkertaistettu datan käyttö: Asiakkaat ovat vuorovaikutuksessa yhden GraphQL-päätepisteen kanssa riippumatta taustalla olevista datalähteistä.
• Parempi suorituskyky: Datanhaku on optimoitu hakemalla vain tarvittavat tiedot kustakin aligraafista.
• Lisääntynyt skaalautuvuus: Jokainen aligraafi voidaan skaalata itsenäisesti, mikä mahdollistaa paremman resurssien käytön.
• Hajautettu kehitys: Tiimit voivat kehittää ja ottaa käyttöön aligraafeja itsenäisesti, mikä edistää ketteryyttä ja innovaatiota.
• Skeeman hallinta: Federaatioyhdyskäytävä valvoo skeeman johdonmukaisuutta ja yhteensopivuutta aligraafien välillä.

Työkalut GraphQL-federaatioon

• Apollo Federation: Suosittu avoimen lähdekoodin toteutus GraphQL-federaatiosta, joka tarjoaa yhdyskäytävän, skeemarekisterin ja työkalut federoitujen GraphQL API:den rakentamiseen ja hallintaan. Apollo Federation tunnetaan skaalautuvuudestaan ja vankasta virheenkäsittelystään.
• GraphQL Hive: Tämä työkalu tarjoaa skeemarekisterin ja hallinnoinnin GraphQL-federoiduille palveluille, tarjoten ominaisuuksia kuten muutosten havaitsemisen, käyttöanalyysin ja skeematarkistukset. Se parantaa supergraafin näkyvyyttä ja hallintaa.

Skeemojen yhdistäminen (Schema Stitching): Vaihtoehtoinen lähestymistapa

Mitä on skeemojen yhdistäminen?

Skeemojen yhdistäminen (Schema Stitching) on toinen tekniikka useiden GraphQL-skeemojen yhdistämiseksi yhdeksi yhtenäiseksi skeemaksi. Toisin kuin federaatiossa, skeemojen yhdistäminen sisältää tyypillisesti manuaalisemman prosessin, jossa määritellään, miten eri skeemojen tyypit ja kentät yhdistetään toisiinsa. Vaikka federaatiota pidetään modernimpana ja vankempana ratkaisuna, skeemojen yhdistäminen voi olla varteenotettava vaihtoehto yksinkertaisemmissa käyttötapauksissa tai siirryttäessä olemassa olevista GraphQL API:sta.

Miten skeemojen yhdistäminen toimii

1. Skeeman määrittely: Jokainen mikropalvelu paljastaa GraphQL API:n omalla skeemallaan.
2. Yhdistämislogiikka: Yhdistämiskerros (usein toteutettu kirjastoilla, kuten GraphQL Tools) määrittelee, miten eri skeemojen tyypit ja kentät yhdistetään. Tämä sisältää resolver-funktioiden kirjoittamisen, jotka hakevat dataa taustapalveluista ja mappavat sen yhtenäiseen skeemaan.
3. Yhtenäinen skeema: Yhdistämiskerros yhdistää yksittäiset skeemat yhdeksi yhtenäiseksi skeemaksi, joka paljastetaan asiakkaalle.

Esimerkki: Tuotteiden ja arvostelujen yhdistäminen

Kuvitellaan kaksi erillistä GraphQL-palvelua: yksi tuotteille ja toinen arvosteluille.

• Tuotepalvelu: Tarjoaa tietoa tuotteista (ID, nimi, kuvaus, hinta).
• Arvostelupalvelu: Tarjoaa arvosteluja tuotteille (ID, tuotteen ID, arvosana, kommentti).

Käyttämällä skeemojen yhdistämistä voit luoda yhtenäisen skeeman, joka antaa asiakkaille mahdollisuuden hakea tuotetiedot ja arvostelut yhdellä kyselyllä.

Määrittäisit yhdistämiskerrokseen resolver-funktion, joka hakee arvostelut tietylle tuote-ID:lle arvostelupalvelusta ja lisää ne Product-tyyppiin yhtenäisessä skeemassa.

// Esimerkki (käsitteellinen): Yhdistämislogiikka GraphQL Tools -kirjastolla
const { stitchSchemas } = require('@graphql-tools/stitch');

const productsSchema = ... // Määritä tuoteskeema
const reviewsSchema = ... // Määritä arvosteluskeema

const stitchedSchema = stitchSchemas({
  subschemas: [
    {
      schema: productsSchema,
    },
    {
      schema: reviewsSchema,
      transforms: [
        {
          transformSchema: (schema) => schema,
          transformRequest: (originalRequest) => {
            return originalRequest;
          },
          transformResult: (originalResult) => {
            return originalResult;
          }
        }
      ],
    },
  ],
  typeDefs: `
    extend type Product {
      reviews: [Review]
    }
  `,
  resolvers: {
    Product: {
      reviews: {
        resolve: (product, args, context, info) => {
          // Hae tuotteen arvostelut arvostelupalvelusta
          return fetchReviewsForProduct(product.id);
        },
      },
    },
  },
});

Tämä esimerkki havainnollistaa skeemojen yhdistämisen ydinkonseptia. Huomaa tarve mukautetuille resolvereille `reviews`-kentän hakemiseksi. Tämä ylimääräinen koodaustyö resolvereiden luomiseksi jokaista suhdetta varten voi hidastaa kehitysprosessia federaatioon verrattuna.

Skeemojen yhdistämisen edut

• Yhtenäinen API: Asiakkaat käyttävät yhtä GraphQL-päätepistettä, mikä yksinkertaistaa datan käyttöä.
• Inkrementaalinen käyttöönotto: Skeemojen yhdistäminen voidaan toteuttaa vaiheittain, mikä mahdollistaa asteittaisen siirtymisen yhtenäiseen API:hin.
• Joustavuus: Skeemojen yhdistäminen antaa enemmän hallintaa skeemojen yhdistämistapaan, mikä mahdollistaa yhdistämislogiikan räätälöinnin erityistarpeisiin.

Skeemojen yhdistämisen haitat

• Manuaalinen konfigurointi: Skeemojen yhdistäminen vaatii yhdistämislogiikan manuaalista konfigurointia, mikä voi olla monimutkaista ja aikaa vievää.
• Suorituskyvyn lisäkustannukset: Resolver-funktiot voivat aiheuttaa suorituskyvyn lisäkustannuksia, erityisesti jos ne sisältävät monimutkaisia datamuunnoksia.
• Rajoitettu skaalautuvuus: Skeemojen yhdistämistä voi olla vaikeampi skaalata kuin federaatiota, koska yhdistämislogiikka on tyypillisesti keskitetty.
• Skeeman omistajuus: Voi johtaa epäselvyyksiin skeeman omistajuudesta, erityisesti jos eri tiimit hallinnoivat yhdistettyjä palveluita.

Työkalut skeemojen yhdistämiseen

• GraphQL Tools: Suosittu kirjasto GraphQL-skeemojen rakentamiseen ja käsittelyyn, sisältäen tuen skeemojen yhdistämiselle.
• GraphQL Mesh: GraphQL Mesh mahdollistaa GraphQL-kyselykielen käytön datan hakemiseen eri lähteistä, kuten REST API:sta, tietokannoista ja gRPC:stä. Se voi yhdistää nämä API:t yhtenäiseksi GraphQL-skeemaksi.

GraphQL-federaatio vs. skeemojen yhdistäminen: Vertailu

Sekä GraphQL-federaatio että skeemojen yhdistäminen tarjoavat keinoja yhdistää useita GraphQL-skeemoja yhdeksi API-rajapinnaksi, mutta ne eroavat lähestymistavaltaan ja ominaisuuksiltaan.

Ominaisuus	GraphQL-federaatio	Skeemojen yhdistäminen
Lähestymistapa	Hajautettu, automatisoitu koostaminen	Keskitetty, manuaalinen konfigurointi
Monimutkaisuus	Matalampi ylläpidon ja skaalauksen monimutkaisuus	Korkeampi monimutkaisuus manuaalisen resolver-logiikan vuoksi
Skaalautuvuus	Suunniteltu suuriin, hajautettuihin järjestelmiin	Vähemmän skaalautuva, käytetään tyypillisesti pienemmissä sovelluksissa
Skeeman hallinta	Sisäänrakennettu skeemanhallinta ja validointi	Vaatii manuaalista skeemanhallintaa ja koordinointia
Työkalut	Vahva työkalujen ja kirjastojen ekosysteemi (esim. Apollo Federation)	Vaatii enemmän räätälöityjä työkaluja ja konfigurointia
Käyttötapaukset	Mikropalveluarkkitehtuurit, suuret API:t, hajautettu kehitys	Pienemmät sovellukset, inkrementaalinen migraatio, erityiset räätälöintivaatimukset

Milloin käyttää GraphQL-federaatiota: Valitse federaatio, kun sinulla on monimutkainen mikropalveluarkkitehtuuri, tarvitset API:n skaalaamista ja haluat antaa itsenäisille tiimeille vallan hallita omia aligraafejaan. Se myös yksinkertaistaa skeemanhallintaa.

Milloin käyttää skeemojen yhdistämistä: Harkitse skeemojen yhdistämistä, kun sinulla on yksinkertaisempi API, tarvitset enemmän hallintaa yhdistämislogiikkaan tai olet siirtymässä olemassa olevista GraphQL API:sta. Ole kuitenkin tietoinen mahdollisista monimutkaisuuksista ja skaalautuvuusrajoituksista.

Autentikoinnin ja auktorisoinnin toteuttaminen

Riippumatta siitä, valitsetko GraphQL-federaation vai skeemojen yhdistämisen, autentikoinnin ja auktorisoinnin toteuttaminen on ratkaisevan tärkeää Frontend API-yhdyskäytäväsi suojaamiseksi. Voit käyttää useita lähestymistapoja:

• Yhdyskäytävätason autentikointi: API-yhdyskäytävä käsittelee autentikoinnin ja auktorisoinnin ennen pyyntöjen reitittämistä taustapalveluihin. Tämä lähestymistapa keskittää turvallisuuslogiikan ja yksinkertaistaa taustapalveluita. Yleisiä menetelmiä ovat JWT (JSON Web Token) -validointi ja OAuth 2.0.
• Palvelutason autentikointi: Jokainen taustapalvelu käsittelee oman autentikointinsa ja auktorisointinsa. Tämä lähestymistapa tarjoaa tarkemman turvallisuuden hallinnan, mutta voi olla monimutkaisempi hallita.
• Hybridimalli: Yhdistelmä yhdyskäytävätason ja palvelutason autentikointia. Yhdyskäytävä hoitaa alkuperäisen autentikoinnin, ja taustapalvelut suorittavat tarkempia auktorisointitarkistuksia.

Esimerkki: JWT-autentikointi Apollo Federationin kanssa

Apollo Federationin avulla voit konfiguroida yhdyskäytävän validoimaan pyyntöjen otsakkeisiin sisältyvät JWT-tokenit. Yhdyskäytävä voi sitten välittää tokenista poimitut käyttäjätiedot aligraafeille, jotka voivat käyttää näitä tietoja auktorisointiin.

// Esimerkki (käsitteellinen): Apollo Gateway -konfiguraatio JWT-validoinnilla
const { ApolloGateway } = require('@apollo/gateway');

const gateway = new ApolloGateway({
  serviceList: [
    // ... aligraafiesi konfiguraatiot
  ],
  buildService: ({ name, url }) => {
    return new MyCustomService({
      name,  // Aligraafin nimi
      url,   // Aligraafin URL
    });
  },
});

class MyCustomService extends RemoteGraphQLDataSource {
  willSendRequest({ request, context }) {
    // Hae käyttäjä kontekstista
    const user = context.user;

    // Lisää käyttäjän ID pyynnön otsakkeisiin
    if (user) {
      request.http.headers.set('user-id', user.id);
    }
  }
}

Tässä esimerkissä luodaan mukautettu palvelu muokkaamaan lähteviä pyyntöjä niin, että ne sisältävät JWT:stä johdetun käyttäjätunnuksen. Alemman tason palvelut voivat sitten käyttää tätä tunnusta auktorisointitarkistuksiin.

Välimuististrategiat suorituskyvyn optimoimiseksi

Välimuistiin tallentaminen on välttämätöntä Frontend API-yhdyskäytävän suorituskyvyn parantamiseksi. Tallentamalla usein käytettyä dataa välimuistiin voit vähentää taustapalveluiden kuormitusta ja parantaa asiakkaiden vastausaikoja. Tässä on joitain välimuististrategioita:

• HTTP-välimuisti: Hyödynnä HTTP-välimuistimekanismeja (esim. `Cache-Control`-otsakkeet) vastausten tallentamiseksi selaimeen ja välityspalvelimiin.
• Muistinsisäinen välimuisti: Käytä muistinsisäisiä välimuisteja (esim. Redis, Memcached) usein käytetyn datan tallentamiseen yhdyskäytävällä.
• CDN-välimuisti: Hyödynnä sisällönjakeluverkkoja (CDN) staattisten resurssien ja API-vastausten tallentamiseen lähemmäs asiakasta.
• GraphQL-kyselyjen välimuisti: Tallenna GraphQL-kyselyiden tulokset niiden kyselymerkkijonon ja muuttujien perusteella. Tämä voi olla erityisen tehokasta usein suoritettaville kyselyille. Apollo Server tarjoaa sisäänrakennetun tuen kyselyjen välimuistille.

Välimuistia toteuttaessasi harkitse välimuistin mitätöintistrategioita varmistaaksesi, että asiakkaat saavat ajantasaista dataa. Yleisiä strategioita ovat:

• Aikapohjainen vanheneminen: Aseta kiinteä vanhenemisaika välimuistiin tallennetulle datalle.
• Tapahtumapohjainen mitätöinti: Mitätöi välimuisti, kun data muuttuu taustapalveluissa. Tämä voidaan saavuttaa webhookien tai viestijonojen avulla.

Valvonta ja havaittavuus

Valvonta ja havaittavuus ovat kriittisiä Frontend API-yhdyskäytäväsi terveyden ja suorituskyvyn varmistamiseksi. Toteuta kattava valvonta seurataksesi keskeisiä mittareita, kuten:

• Pyynnön viive: Aika, joka kuluu pyynnön käsittelyyn.
• Virheprosentit: Virheisiin johtavien pyyntöjen prosenttiosuus.
• Suoritusteho: Käsiteltyjen pyyntöjen määrä aikayksikössä.
• Resurssien käyttö: Yhdyskäytävän ja taustapalveluiden suorittimen, muistin ja verkon käyttö.

Käytä jäljitystä (tracing) pyyntöjen seuraamiseen niiden kulkiessa järjestelmän läpi, tunnistaen pullonkauloja ja suorituskykyongelmia. Lokitiedot tarjoavat arvokasta tietoa yhdyskäytävän ja taustapalveluiden toiminnasta.

Valvonnan ja havaittavuuden työkaluja ovat muun muassa:

• Prometheus: Avoimen lähdekoodin valvonta- ja hälytysjärjestelmä.
• Grafana: Datan visualisointi- ja valvontatyökalu.
• Jaeger: Avoimen lähdekoodin hajautettu jäljitysjärjestelmä.
• Datadog: Valvonta- ja tietoturvaalusta pilvisovelluksille.
• New Relic: Digitaalinen älykkyysalusta ohjelmistojen suorituskyvyn valvontaan ja parantamiseen.

Toteuttamalla vankan valvonnan ja havaittavuuden voit proaktiivisesti tunnistaa ja ratkaista ongelmia, varmistaen Frontend API-yhdyskäytäväsi luotettavuuden ja suorituskyvyn.

Yhteenveto

GraphQL-federaatiolla tai skeemojen yhdistämisellä rakennettu Frontend API-yhdyskäytävä voi merkittävästi yksinkertaistaa datan käyttöä, parantaa suorituskykyä ja tehostaa kehittäjäkokemusta moderneissa verkkosovelluksissa. GraphQL-federaatio tarjoaa tehokkaan ja skaalautuvan ratkaisun hajautettujen GraphQL API:den koostamiseen, kun taas skeemojen yhdistäminen tarjoaa joustavamman lähestymistavan olemassa olevien skeemojen yhdistämiseen. Harkitsemalla huolellisesti sovelluksesi erityisvaatimuksia ja näiden tekniikoiden välisiä kompromisseja voit valita parhaan lähestymistavan vankan ja tehokkaan Frontend API-yhdyskäytävän rakentamiseen.

Muista toteuttaa asianmukainen autentikointi ja auktorisointi, välimuististrategiat sekä valvonta ja havaittavuus varmistaaksesi yhdyskäytäväsi turvallisuuden, suorituskyvyn ja luotettavuuden. Noudattamalla näitä parhaita käytäntöjä voit hyödyntää GraphQL:n koko potentiaalin ja rakentaa moderneja verkkosovelluksia, jotka tarjoavat poikkeuksellisia käyttäjäkokemuksia.